Skip to content

docs: retire memory-bank after folding its last unique facts into docs - #889

Merged
TomKaltofen merged 1 commit into
mainfrom
docs/retire-memory-bank
Jul 30, 2026
Merged

docs: retire memory-bank after folding its last unique facts into docs#889
TomKaltofen merged 1 commit into
mainfrom
docs/retire-memory-bank

Conversation

@TKaltofen

Copy link
Copy Markdown
Collaborator

Answers the question "can memory-bank/ be dropped?" with: yes, but not by deleting it, because one thing in it was both unique and more current than its public counterpart.

What was in there

memory-bank/ was a second documentation tree that nothing depended on: no mkdocs.yml nav entry, no sdist entry, no tox.ini or CI reference, no .claude/ reference. Only CLAUDE.md and AGENTS.md pointed at it. It had already shrunk from ten files to two, and that pass also had to delete six stale files and correct a skip count that had drifted. #800 closed on the same premise: stale context in these files misdirects work.

Auditing what was left, everything was covered elsewhere:

Content Already in
Architecture, component roles docs/docs/index.md, mloda/core/README.md
Transformations over static states docs/docs/faq.md
Dependency-free core, backends as optional extras docs/docs/chapter1/compute-frameworks.md
PropertySpec lifecycle docs/docs/in_depth/property-mapping.md
Cross-repo downstream migration state the owning issues in #761, phase 6
Declared vs effective options per stage nowhere else

The part worth keeping

in_depth/property-mapping.md calls itself the single source of truth for the option model, but it still said materialization happens "centrally at the compute boundary" and that it "never changes matching or FeatureSet splitting". The compute boundary is now the idempotent safety net, not the primary site, and the splitting half is false: Engine.add_feature_to_collection rebinds options as a feature enters the plan, precisely so default-equivalent twins canonicalize before splitting. The memory bank described this correctly, so the public page was the stale one.

That section is corrected, the declared-vs-effective stage table moves in beside it, and two tests that already pin this behavior join the invariant map. The corrected text also spells out three things the page never stated: that the engine warns on a default-equivalent merge and that the survivor's dependency declaration comes from the first-listed request, that the direct FeatureSet path raises rather than merging, and that filter matching calls match_feature_group_criteria again after intake and therefore sees effective options where resolution saw declared ones.

Then the directory goes. CLAUDE.md and AGENTS.md trade their Memory Bank section for a pointer to the documentation that is actually maintained, including the in-tree READMEs, and the transient phased-work todo.md moves to the repository root and is gitignored.

Validation

tox green: 7374 passed, 170 skipped, plus ruff format, ruff check, licenses, mypy --strict, bandit. The python314 env, which is the only one that executes documentation tests, was run separately. The documentation additions are prose and a table, so no new executable code block enters the mktestdocs suite.

The directory was a second, ungated documentation tree. Auditing what was left in
it, everything was already covered elsewhere except one table:

- Architecture and component roles: docs/docs/index.md, mloda/core/README.md
- Transformations over static states: docs/docs/faq.md
- Dependency-free core, backends as optional extras: chapter1/compute-frameworks.md
- PropertySpec lifecycle: in_depth/property-mapping.md
- Cross-repo downstream state: the owning issues listed in epic #761, phase 6

The exception is the table recording which lifecycle stage observes declared
(pre-default) options and which observes effective (post-default) ones. It moves
into in_depth/property-mapping.md beside the materialization rules, along with
three things that page does not state: the compute-boundary call is an idempotent
no-op once intake has run, and carries the work only for direct FeatureSet use
where colliding twins raise instead of merging; validate_input_features runs
before that safety net on the direct path; and GlobalFilter calls
match_feature_group_criteria again after intake, so the one classmethod observes
both views. The filter pin joins the invariant map.

CLAUDE.md and AGENTS.md lose their Memory Bank section in favor of a pointer to
the documentation that is actually maintained, and the transient phased-work
todo.md moves to the repository root, now gitignored.

removes the surface instead of refreshing it a third time.
@TKaltofen
TKaltofen force-pushed the docs/retire-memory-bank branch from 33ec1ec to 39b07b2 Compare July 30, 2026 16:40
@TomKaltofen
TomKaltofen merged commit f8621d0 into main Jul 30, 2026
18 checks passed
@TomKaltofen
TomKaltofen deleted the docs/retire-memory-bank branch July 30, 2026 16:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants